Crate async_once_cell

A collection of lazy initialized values that are created by Futures.

OnceCell’s API should be familiar to anyone who has used the once_cell crate or the proposed std::cell::OnceCell. It provides an async version of a cell that can only be initialized once, permitting tasks to wait on the initialization if it is already running instead of racing multiple initialization tasks.

Unlike threads, tasks can be cancelled at any point where they block. OnceCell deals with this by allowing another initializer to run if the task currently initializing the cell is dropped. This also allows for fallible initialization using OnceCell::get_or_try_init, and for the initializing Future to contain borrows or use references to thread-local data.

Lazy takes the opposite approach: it wraps a single Future which is cooperatively run to completion by any polling task. This requires that the initialization function be independent of the calling context, but will never restart an initializing function just because the surrounding task was cancelled.

Overhead

Both cells use two usizes to store state and do not retain any allocations after initialization is complete. OnceCell and Lazy only allocate if there is contention.

Features

The critical-section feature

If this feature is enabled, the critical-section crate is used instead of an std mutex. You must depend on that crate and select a locking implementation; see its documentation for details.

The unpin feature

This feature enables the unpin module which contains an alternative API for Lazy that does not rely on pinning the object during initialization, even for futures that are not Unpin. In general, prefer the types in the crate root and, if needed, box futures to make them unpin.

The std feature

This is currently a no-op, but might in the future be used to expose APIs that depends on types only in std. It does not control the locking implementation.

Modules

• unpin
  Types that do not rely on pinning during initialization.

Structs

• Lazy
  A value which is computed on demand by running a future.
• OnceCell
  A cell which can be written to only once.